compilers (names ending in ".µ" for Metrowerks CodeWarrior and ".π" for THINK C). Users of older versions of the compilers (e.g. THINK C 6 or CW6) unfortunately can't use the new projects: complain to the authors of the compilers, who seem to have no compunction about changing the project format every time they release a new version. I suggest you upgrade to the current version; see "Advice".
All the programs that do accurate luminance control use the monitor-calibration data stored in LuminanceRecord1.h (the number is a screen number, similar--but not identical--to the number that appears in the Monitors control panel). These calibration files describe one of my monitors (an Apple High-Resolution Monochrome), and, naturally, before doing any serious data collection you should create new files that describe your own monitors. Use the CalibrateLuminance program and a photometer.
DON'T BOTHER WITH PIXMAPS, JUST USE WINDOWS AND GWORLDS: and use CopyWindows instead of CopyBits or CopyBitsQuickly. CopyBits is one of Apple's more impressive routines. It's powerful and fast. For my purposes its only drawback is that I haven't always been able to prevent it from doing color translations. So I wrote CopyBitsQuickly to copy images without color translations. (A long time ago CopyBits used to be slow, but that's history. At present CopyBitsQuickly is approximately the same speed as CopyBits, except when doing image expansion, for which it is much faster than CopyBits.) However, both CopyBits and CopyBitsQuickly require you to supply pixmap pointers, which can be a nuisance. These days, our programs use windows (created by GDOpenWindow or NewCWindow) and GWorlds (which are really offscreen windows, created by NewGWorld). Extracting the pixmap's pointer from the guts of the window is straightforward but messy (see BitMapPtr in GDOpenWindow.c). Now you don't have to bother. Just call CopyWindows.c. Its first two arguments are the source and destination windows. The rest of the arguments are like those for CopyBits or CopyBitsQuickly. It makes your programs much easier to write and read, and probably makes them more robust because there are a lot of subtle and fragile assumptions that people often make in calling CopyBits, which CopyWindows takes care of for you. Look at the demo NoiseVBL.c.
NUMERICAL RECIPES IN C:
A few programs in the VideoToolbox (CalibrateLuminance.c, DrawGrating.c, PsychometricFit.c, and Quick3) use the (very handy) Numerical Recipes software and book. Required changes to these routines are described in the "Improve Numerical Recipes" document in the Notes folder. I have included pre-compiled CalibrateLuminance and Quick3 applications for users that don't have the Numerical Recipes. The Numerical Recipes C Set for Macintosh (main book, example book, and disk) costs $90 from:
Cambridge University Press
Orders Department
110 Midland Avenue
Port Chester, NY 10573
1-(800)-227-0247
<SANE.h> IS DEAD. LONG LIVE <fp.h>:
In going to the PowerPC, Apple wisely decided to drop <SANE.h>, i.e. their Standard Apple Numerics Environment routines, in favor of <fp.h>, i.e. the Floating-Point C Extensions (FPCE) proposed by the Numerical C Extensions Group (NCEG). SANE was uselessly slow anyway since it was tied to 10-byte doubles, whereas the 68881 floating point chip used 12-byte doubles. The <fp.h> extensions are very welcome, providing some handy math functions and providing standard ways of producing and testing for NAN and INF. <fp.h> provides standard routines very similar to the VideoToolbox routines IsNan and IsFinite. I would suggest favoring the fp.h routines since they are becoming standard. If you have any programs that use <SANE.h>, you should think about using <fp.h> instead. Note that VideoToolbox.h now automatically includes fp.h, if available, and otherwise includes math.h.
PORTABILITY:
Various issues to do with porting programs among different computers and compilers are discussed in the "Portability" document.
BUGS & SUGGESTIONS:
It's unlikely that you'll find any bugs, but if you do, please send me email so we can fix 'em. Suggestions and code donations (i.e. C routines to be included in the VideoToolbox, possibly in modified form, with full attribution) are warmly appreciated. Also many people have contributed useful paragraphs, which appear in the VideoToolbox notes, with attribution, about specific technical issues that they identified and perhaps solved.
denis@xp.psych.nyu.edu
NOT MULTIFINDER FRIENDLY:
Walt Makous writes, "I ran Sandstorm by clicking on the icon for the application, interrupted it by clicking outside the window, and then resumed it by clicking on the window again. This locks the keyboard so that the only way I can get back control is by using the programmer's switch." REPLY: Alas, I've never had any need to write polite applications that gracefully share the computer with other applications. Experiments always seem to deserve hogging it all. The Sandstorm demo allows you to invoke other applications, because it doesn't obscure the whole window, but it doesn't act like a good citizen in paying attention to the messages it gets from the Finder about what happened. (I would go ahead and make the demos multifinder-friendly if I knew how, but it hasn't seemed worth learning just for the sake of the demos.)
BLOCKMOVEDATA:
BlockMoveData is a new (as of System Update 3.0 to System 7.1) variant of BlockMove that omits cache flushing. Calling BlockMoveData() on earlier versions of the operating system will invoke plain old BlockMove(). BlockMove is coded in each computer's ROM to implement the fastest possible move. E.g. it uses the MOVE16 instruction on the 68040 processor. It may be faster than the generic code that most C compilers produce. When the Quadra's were released, Apple added code to the BlockMove trap to flush the instruction cache each time BlockMove was called, just in case the move was copying instructions that were in the cache. However, flushing the cache everytime you call BlockMove sacrifices the speed benefit of the cache, making it less advantageous to call BlockMove. In System Update 3.0 Apple finally gave developers a way of telling BlockMove not to flush the cache. You call BlockMoveData instead. However, if run on computers lacking System Update 3.0 the flag bit distinguishing BlockMoveData from the old BlockMove will be ignored and the cache will be flushed, which will slow you down. BlockMoveData() is defined in Apple's Memory.h in Apple's new Universal Header files, but is not defined in pre-Universal header files. VideoToolbox.h tests for that case and, if necessary, defines BlockMoveData, so that you may use it freely.
68040:
Peter Lennie writes (6/23/93): "On the latest developers CD [June? '93] there's a note about the Quadra's use of a trap to emulate the FINTRZ instruction, which isn't built into the 68040. This instruction is called commonly in the code generated by THINK C [5, when FPU use is enabled], and for me it became an issue in the loops that recalculate lookup tables during chromatic flicker. By rewriting the loop to avoid that instruction (using a small function supplied on the CD) I reduced the time it took to recalculate --as opposed to write-- the tables from 16msec to 1.6 msec." [Does anyone know whether this concern is still applicable to the current version? I don't use the Quadra. dgp]
DISCLAIMER (included at the request of the MacPsych archive):
The VideoToolbox is provided "as is" without warranty of any kind. Denis Pelli, New York University, SCiP, the operators of MacPsych, and St. Olaf College make no claims concerning the accuracy or correctness of the computer code contained in, or the results of the use of VideoToolbox. The entire risk as to the results and performance of VideoToolbox is assumed by you. If the VideoToolbox is defective you, and not Denis Pelli, New York University, SCiP, the operators of MacPsych, or St. Olaf College assume the entire cost of all necessary servicing, repair or correction.
